Add pathMappings option to debugger #2251

jborean93 · 2025-07-31T06:00:05Z

PR Summary

Adds the pathMappings option to the debugger that can be used to map a local to remote path and vice versa. This is useful if the local environment has a checkout of the files being run on a remote target but at a different path. The mappings are used to translate the paths that will the breakpoint will be set to in the target PowerShell instance. It is also used to update the stack trace paths received from the remote.

For a launch scenario, the path mappings are also used when launching a script if the integrated terminal has entered a remote runspace.

PR Context

Fixes: #2242

Copilot

Pull Request Overview

This PR adds a pathMappings option to the PowerShell debugger that enables mapping between local and remote file paths during debugging sessions. This is particularly useful when debugging remote PowerShell instances where the local development environment has the same files but at different paths.

Key changes:

Adds PathMapping record to define local-to-remote path mappings
Integrates path mapping logic into breakpoint setting, stack trace handling, and script launching
Adds comprehensive end-to-end test for attach scenarios with path mappings

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
PathMapping.cs	New record defining the structure for local/remote path mappings
DebugService.cs	Core path mapping logic with methods to translate between local and remote paths
LaunchAndAttachHandler.cs	Integration of path mappings into launch and attach request handling
StackTraceHandler.cs	Updates stack trace paths using path mappings for remote debugging
BreakpointService.cs	Modified to use mapped paths when setting breakpoints
BreakpointApiUtils.cs	Added script path override parameter for breakpoint setting
DisconnectHandler.cs	Cleanup of path mappings on disconnect
DscBreakpointCapability.cs	Minor refactor to extract module name instead of full module info
DebugAdapterProtocolMessageTests.cs	Comprehensive E2E test for path mapping functionality

Comments suppressed due to low confidence (1)

test/PowerShellEditorServices.Test.E2E/DebugAdapterProtocolMessageTests.cs:580

Spelling error: 'cotinue' should be 'continue'.

                // background and requesting the st is the only wait to ensure

src/PowerShellEditorServices/Services/DebugAdapter/PathMapping.cs

test/PowerShellEditorServices.Test.E2E/DebugAdapterProtocolMessageTests.cs

Copilot · 2025-07-31T06:01:07Z

src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs

+                    if (remotePath.StartsWith(mapping.RemoteRoot, StringComparison.OrdinalIgnoreCase))
+                    {
+                        localPath = mapping.LocalRoot + remotePath.Substring(mapping.RemoteRoot.Length);


Path comparison using StartsWith without ensuring proper path separators could lead to incorrect matches. For example, '/home/user' would incorrectly match '/home/username/file.ps1'. Consider using proper path comparison logic that respects directory boundaries.

Suggested change

if (remotePath.StartsWith(mapping.RemoteRoot, StringComparison.OrdinalIgnoreCase))

{

localPath = mapping.LocalRoot + remotePath.Substring(mapping.RemoteRoot.Length);

string normalizedRemotePath = Path.GetFullPath(remotePath);

string normalizedRemoteRoot = Path.GetFullPath(mapping.RemoteRoot);

if (normalizedRemotePath.StartsWith(normalizedRemoteRoot, StringComparison.OrdinalIgnoreCase) &&

Path.GetRelativePath(normalizedRemoteRoot, normalizedRemotePath).IndexOf("..", StringComparison.Ordinal) != 0)

{

localPath = Path.Combine(mapping.LocalRoot, Path.GetRelativePath(normalizedRemoteRoot, normalizedRemotePath));

In this case it is use supplied values. if they wish to not use a directory separator at the end of the localRoot or remoteRoot then that's their decision. The path mappings is designed to replace the root substring with the specified equivalent.

Copilot · 2025-07-31T06:01:08Z

src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs

+                        continue;
+                    }
+
+                    if (localPath.StartsWith(mapping.LocalRoot, StringComparison.OrdinalIgnoreCase))


Same path comparison issue as with TryGetMappedLocalPath. Using StartsWith without proper path boundary checking could lead to incorrect path mappings.

Suggested change

if (localPath.StartsWith(mapping.LocalRoot, StringComparison.OrdinalIgnoreCase))

if (localPath.StartsWith(mapping.LocalRoot, StringComparison.OrdinalIgnoreCase) &&

(localPath.Length == mapping.LocalRoot.Length ||

localPath[mapping.LocalRoot.Length] == System.IO.Path.DirectorySeparatorChar ||

localPath[mapping.LocalRoot.Length] == System.IO.Path.AltDirectorySeparatorChar))

See #2251 (comment)

jborean93 · 2025-07-31T06:03:34Z

An example of how the pathMappings can be used for launching when the interactive terminal has entered a remote runspace. The editor sees the file under /home/jborean/dev/vscode-powershell/examples/test.ps1 but the pathMappings will map it to C:\temp\test.ps1 where that same script is located on the remote host.

{
  "name": "PowerShell Launch Script",
  "type": "PowerShell",
  "request": "launch",
  "script": "${workspaceFolder}/test.ps1",
  "cwd": "${cwd}",
  "pathMappings": [
    {
      "localRoot": "${workspaceFolder}/",
      "remoteRoot": "C:\\temp\\"
    }
  ]
},

It looks like I need to update the logic for the client breakpoint to contain the original workspace path and not the mapped remote file so I will fix that.

Adds the `pathMappings` option to the debugger that can be used to map a local to remote path and vice versa. This is useful if the local environment has a checkout of the files being run on a remote target but at a different path. The mappings are used to translate the paths that will the breakpoint will be set to in the target PowerShell instance. It is also used to update the stack trace paths received from the remote. For a launch scenario, the path mappings are also used when launching a script if the integrated terminal has entered a remote runspace.

andyleejordan · 2025-08-26T19:25:27Z

src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs

+        internal void SetPathMappings(PathMapping[] pathMappings) => _pathMappings = pathMappings;
+
+        internal void UnsetPathMappings() => _pathMappings = null;


Could this just be a property?

andyleejordan · 2025-08-26T19:26:50Z

src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs

+
+        internal bool TryGetMappedLocalPath(string remotePath, out string localPath)
+        {
+            if (_pathMappings is not null)


If _pathMappings is initialized to an empty dictionary then foreach over it in that scenario is a no-op and we don't have to do this check (and nested statement).

andyleejordan · 2025-08-26T19:30:32Z

src/PowerShellEditorServices/Services/DebugAdapter/DebugService.cs

+
+                    if (remotePath.StartsWith(mapping.RemoteRoot, StringComparison.OrdinalIgnoreCase))
+                    {
+                        localPath = mapping.LocalRoot + remotePath.Substring(mapping.RemoteRoot.Length);


It does seem to me like the mapping would also be a directory (which may or may not be supplied with a trailing path separator); is there a good reason not to use path.combine?

andyleejordan · 2025-08-26T19:37:05Z

src/PowerShellEditorServices/Services/DebugAdapter/Handlers/LaunchAndAttachHandler.cs

+            catch
+            {
+                _debugService.UnsetPathMappings();
+                throw;


I feel like there's a better pattern to apply here, but I'm not sure what. @SeeminglyScience for a suggestion (is there a way this can be done with a using? Is that too complicated?)

@jborean93 should this be a finally instead of a catch? or are the path mappings unset somewhere else when there's no error? I guess that would have to be the case right? Handle returns before debugging is actually complete right?

(if the answer to the above is "no it needs to be a catch", then @andyleejordan: nah using wouldn't work here unfortunately as it's only unset when an exception occurs)

andyleejordan · 2025-08-26T19:38:41Z

src/PowerShellEditorServices/Services/DebugAdapter/Handlers/LaunchAndAttachHandler.cs

+                {
+                    // If the script is not mapped, we will map it to the remote path
+                    // using the RemoteFileManagerService.
+                    _debugStateService.ScriptToLaunch =


Can you simplify this so the assignment to ScriptToLaunch happens only once, with the if/else covering the two logical paths to get the (err) path?

andyleejordan · 2025-08-26T19:39:14Z

src/PowerShellEditorServices/Services/DebugAdapter/Handlers/LaunchAndAttachHandler.cs

                return await HandleImpl(request, cancellationToken).ConfigureAwait(false);
            }
            catch
            {
                _debugService.IsDebuggingRemoteRunspace = false;
+                _debugService.UnsetPathMappings();
                throw;


Ohh I see where that pattern came from now.

andyleejordan · 2025-08-26T19:40:38Z

src/PowerShellEditorServices/Services/DebugAdapter/Handlers/LaunchAndAttachHandler.cs

@@ -486,6 +522,7 @@ private async Task OnExecutionCompletedAsync(Task executeTask)
            _debugEventHandlerService.UnregisterEventHandlers();

            _debugService.IsDebuggingRemoteRunspace = false;
+            _debugService.UnsetPathMappings();


This is probably not actually something to be solved in this PR, it seems like DebugService needs some sort of finalizer to handle "hey we're wrapping up now." Surprised it's not just disposed and recreated but I'd have to dig in to understand that more.

andyleejordan · 2025-08-26T19:41:14Z

src/PowerShellEditorServices/Services/DebugAdapter/Handlers/StackTraceHandler.cs

+        {
+            scriptNameOverride = mappedLocalPath;
+        }
+        StackFrame breakpointLabel = CreateBreakpointLabel(invocationInfo, scriptNameOverride: scriptNameOverride);


This is how I think the other assignment should be done. Much more clear.

andyleejordan · 2025-08-26T19:42:22Z

src/PowerShellEditorServices/Services/PowerShell/Debugging/DscBreakpointCapability.cs

-                IReadOnlyList<PSModuleInfo> dscModule =
-                    await executionService.ExecutePSCommandAsync<PSModuleInfo>(
+                IReadOnlyList<string> dscModule =
+                    await executionService.ExecutePSCommandAsync<string>(


Ok so these are now strings since we added the parameter to get the names instead of the modules directly. Why, what are we changing here? FWIW this is really old legacy code.

andyleejordan · 2025-08-26T19:43:11Z

test/PowerShellEditorServices.Test.E2E/DebugAdapterProtocolMessageTests.cs

                        nextStoppedTcs = new();
+
+                        currentStoppedTcs.SetResult(e);


I feel like this must fix something that's been broken/buggy with the tests. Can you elaborate?

Copilot AI review requested due to automatic review settings July 31, 2025 06:00

Copilot AI reviewed Jul 31, 2025

View reviewed changes

jborean93 closed this Jul 31, 2025

jborean93 reopened this Jul 31, 2025

jborean93 mentioned this pull request Aug 3, 2025

Debug: add pathMappings option PowerShell/vscode-powershell#5254

Open

3 tasks

jborean93 force-pushed the path-mapping branch 2 times, most recently from 0837fa1 to a182fe6 Compare August 5, 2025 19:48

jborean93 force-pushed the path-mapping branch from a182fe6 to 23ef91b Compare August 5, 2025 20:03

jborean93 mentioned this pull request Aug 6, 2025

Delay launch/attach until after config done #2250

Draft

Expose pathMappings to Start-DebugAttachSession and fixup Name

ba8d36c

jborean93 requested a review from a team as a code owner August 18, 2025 22:11

andyleejordan reviewed Aug 26, 2025

View reviewed changes

-                    if (remotePath.StartsWith(mapping.RemoteRoot, StringComparison.OrdinalIgnoreCase))
-                    {
-                        localPath = mapping.LocalRoot + remotePath.Substring(mapping.RemoteRoot.Length);
+                    string normalizedRemotePath = Path.GetFullPath(remotePath);
+                    string normalizedRemoteRoot = Path.GetFullPath(mapping.RemoteRoot);
+                    if (normalizedRemotePath.StartsWith(normalizedRemoteRoot, StringComparison.OrdinalIgnoreCase) &&
+                        Path.GetRelativePath(normalizedRemoteRoot, normalizedRemotePath).IndexOf("..", StringComparison.Ordinal) != 0)
+                    {
+                        localPath = Path.Combine(mapping.LocalRoot, Path.GetRelativePath(normalizedRemoteRoot, normalizedRemotePath));

-                    if (localPath.StartsWith(mapping.LocalRoot, StringComparison.OrdinalIgnoreCase))
+                    if (localPath.StartsWith(mapping.LocalRoot, StringComparison.OrdinalIgnoreCase) &&
+                        (localPath.Length == mapping.LocalRoot.Length ||
+                         localPath[mapping.LocalRoot.Length] == System.IO.Path.DirectorySeparatorChar ||
+                         localPath[mapping.LocalRoot.Length] == System.IO.Path.AltDirectorySeparatorChar))

		internal void SetPathMappings(PathMapping[] pathMappings) => _pathMappings = pathMappings;

		internal void UnsetPathMappings() => _pathMappings = null;

Add pathMappings option to debugger #2251

Are you sure you want to change the base?

Add pathMappings option to debugger #2251

Uh oh!

Conversation

jborean93 commented Jul 31, 2025

PR Summary

PR Context

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jborean93 commented Jul 31, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!